1.3 What Supercite Does

Supercite is invoked for the first time on a reply buffer via your MUA’s reply or forward command. This command will actually perform citations by calling a hook variable to which Supercite’s top-level function sc-cite-original has been added. When sc-cite-original is executed, the original message must be set up in a very specific way, but this is handled automatically by the MUA. See Hints to MUA Authors.

The first thing Supercite does, via sc-cite-original, is to parse through the original message’s mail headers. It saves this data in an information association list, or info alist. The information in this list is used in a number of places throughout Supercite. See Information Keys and the Info Alist.

After the mail header info is extracted, the headers are optionally removed (nuked) from the reply. Supercite then writes a reference header into the buffer. This reference header is a string carrying details about the citation it is about to perform.

Next, Supercite visits each line in the reply, transforming the line according to a customizable “script”. Lines which were not previously cited in the original message are given a citation, while already cited lines remain untouched, or are coerced to your preferred style. Finally, Supercite installs a keymap into the reply buffer so that you have access to Supercite’s post-yank formatting and reciting commands as you subsequently edit your reply. You can tell that Supercite has been installed into the reply buffer because that buffer’s modeline will display the minor mode string ‘SC’.

When the original message is cited by sc-cite-original, it will (optionally) be filled by Supercite. However, if you manually edit the cited text and want to re-fill it, you must use an add-on package such as filladapt or gin-mode. These packages can recognize Supercited text and will fill them appropriately. Emacs’s built-in filling routines, e.g., fill-paragraph, do not recognize cited text and will not re-fill them properly because it cannot guess the fill-prefix being used. See Post-yank Formatting Commands, for details.

As mentioned above, Supercite provides commands to recite or uncite regions of text in the reply buffer, and commands to perform other beautifications on the cited original text, maintaining consistent and informative citations throughout. Supercite tries to be as configurable as possible to allow for a wide range of personalized citation styles, but it is also immediately useful with the default configuration, once it has been properly connected to your MUA. See Getting Connected, for more details.